Amiga Format CD 43/Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso/-serious-/programming/arexx/rexxbgui/rexxbgui.doc

Text File | 1999-06-14 | 19KB | 534 lines

rexxbgui.library version 1.1
Date: April 23, 1999
Copyright © Jilles Tjoelker 1999

New in V2.0:
* Version number bumped because of new functions.
* Added menus.
* Added progress bar (suggested by Ingo ...) and indicator.
* Bug fixed: bguiwindow() did not get the argument count correctly. This
  caused problems, because ARexx does not clear extra argument slots but
  instead leaves in them what values happen to be contained in them from
  previous function calls.

New in V1.1:
* New functions: bguiwinbusy(), bguiwinready(), bguipages(), bguimx(),
  bguiactivategadget(), bguilist(), bguiaddcondit(), bguilistvaddentry(),
  bguilistvcommand(), bguilistvreplacesel()
* New argument for bgui[hv]group(), equal, to force equal width or height
  of the objects in the group
* New argument for bguiwindow(), pos, to open the window on another position
  than centred on the screen
* Some nonfunctional tags removed
* New tags: BT_#?, PAGE_#?, MX_#?, TAG_IGNORE
* Better documentation
* Bug fixed: the library could be flushed from memory when a bguiopen() was
  still outstanding.
* A control-C break is now accepted immediately in bguiwinwaitevent() and
  bguiwait() and passed to ARexx.
* Bug fixed: BGUI 41.10 took the command name, which is always equal to "", for
  the prefs filename. Fixed by temporarily setting the pr_Cli pointer to zero.

Look in the example scripts for more information.
General ARexx limitation: functions can only have up to 15 arguments.

ESCAPE SEQUENCES

Escape sequences can be used in most texts, including labels, frame titles
info object contents and listview entries. Frame titles may have shadow.
Listview entries and labels within objects can be text on background or
filltext on fill; when you change the colours it cannot be restored.
ESC='1b'x or just use the Esc key to put it in a string constant.

ESC||ESC no operation; used to separate sequences ending in a digit
         from normal digits.
ESC'u'   underlined on (do not use for indicating a hotkey)
ESC'b'   bold on
ESC'i'   italics on
ESC'z'   underscore on (can indicate the hotkey for a gadget, only visual
         though, use BT_Key to make it work)
ESC'n'   normal text
ESC'd'n  set DrawInfo pen #n (2=text, 3=shine, 4=shadow, 5=selected gadget
         fill, 6=text on fill, 7=background, 8=important text)
ESC'p'n  set colour #n
ESC'D'n  set DrawInfo pen #n as background
ESC'P'n  set colour #n as background
ESC's'   shadow on (additionally use ESC'd3')
ESC'-'ch turn something off (ch=u/b/i/s/z)
ESC'c'   centre this and the following lines
ESC'r'   right-justify this and the following lines
ESC'l'   left-justify this and the following lines
'0a'x    new line. This does not work for listview entries and frame titles.

FUNCTIONS


success=bguiopen([taskname],[noerrorifopenfail])

This function opens bgui.library. Version 41 is required.
taskname indicates the name of the prefs file, default "ARexx".
Predefined are: ID.WIN(CLOSE|NOMORE|INACTIVE|ACTIVE).
If this function has not yet been called, all functions starting with
'bgui' cause "Error return from function".

x=bguiwait()

Wait for most events; Control-C is passed trough to ARexx
(signal on break_c).

id=bguiwinevent(winobj,[destvar])

This function does not wait for events.

id=bguiwaitwinevent(winobj,[destvar])

This function is much more efficient than the bguiwinevent()/bguiwait()
combination.

success=bguiwinopen(winobj)

This function must be used to open a window. When a window object is created,
it does not open automatically, unlike some other GUI engines' behaviour.
This enables you to do things like bguiwintabcycleorder() in time.

x=bguiwinclose(winobj)


success=bguiwinbusy(winobj)

Use this function to set a busy pointer and zero-size requester that blocks
input on a window. It nests, i.e. the window will not be unblocked until
one bguiwinready() has been done for each bguiwinbusy() executed.

success=bguiwinready(winobj)


obj=bguiwindow(title,mastergroup,[scalew],[scaleh],[refwin],[scrname],[pos],[menu])

scale[wh]: 0% = minimum size, 100% = full screen
Precede scalew and/or scaleh with a minus sign to lock the dimension.
Locking both removes the size gadget.
refwin: the new window object will open on the same screen as refwin
pos 'S' centre on screen
    'M' centre on mouse pointer
    'T' top-left of the screen
    'W' centre on window
    'B' l t w h position in screen (pixel) coordinates
    'R' l t w h centre window on this box
    '*' (anywhere) do not activate window upon opening (doesn't really
        fit here but this saves arguments)
menu: concatenate bguimenu() results

info=bguilayout(tag,value,[tag],[value],...)

Concatenate the return value of this to an object. It does not work for
VarSpace members.

info=bguivarspace(weight)

A weight controlled spacing in a group; 1<weight<1023
bguilayout() cannot be used on this.

obj=bgui[hv]group(objects,[spacing],[offset],[title],[equal])

Double use of objects or forgotten '||' is caught -> error 12.
spacing/offset -1 narrow
               -2 normal
               -3 wide
offset 'F' frame (required for a title)
equal 'W' all objects the same width
      'H' all objects the same height
      'S' all objects the same width and height

obj=bguipages(name,objects)

This function only creates OBJ.name, not ID.name.
Do not set PAGE_Active values which are out of range!
The usage of pages increases the number of objects that can be in a window
and therefore object creation time. The BGUI prefs program is an example of
this!

obj=bguibutton(name,label)

As other "real" gadget creation functions, this one sets both ID.name
(compare with bguiwinevent() or bguiwinwaitevent() result) and OBJ.name (for
bguiget() and similar functions).

Prefix the keyboard shortcut with '_' in label. This also applies to other
gadgets. Take care that all shortcuts are different! BGUI does not check
this (MUI doesn't either). This type of bug is present in much software.

obj=bguitoggle(name,label,[state])


obj=bguicheckbox(name,[label],[state])


obj=bguiinfo(name,[label],contents)

Non-clickable information object.

obj=bguistring(name,[label],[contents],maxchars)


obj=bguiinteger(name,[label],[contents],[maxchars],[min],[max])

It is not guaranteed, that min<=bguiget(int,STRINGA_LongVal)<=max.

obj=bguilistview(name,[label],[stem],[type],[ncolumns])

type 'R' read-only
     'S' select (default)
     'D' drag'n'drop
In multi-column listview entries, the columns are separated by a tab
character. Attributes set with escape sequences do not continue from
one column to the next.
Optionally, you can append column weights to ncolumns, e.g. '3 10 45 45' to
create one small column and two wider ones.

obj=bguimx(name,[label],stem,[type])

type 'R' radio buttons (default)
     'T' tabs
     'U' upside down tabs

obj=bguiprogress(name,[label],min,max,[format],[type])

format: C-style format string for text in the gadget. Use %ld as a
placeholder for the number. Other percent signs must be doubled. Other
possibilities: "%03ld" forces a field size of three digits and pads on the
left with zeroes. "%lD" formats the number according to the language selected
and works only if locale.library is installed. "%lx" creates a hexadecimal
format.
BGUI 41.10 draws the text in the last colour used (if done=max then the
progress bar colour else the background colour) because of a bug, therefore
the format string should begin with ESC'd2'ESC||ESC (not necessarily 2).
ESC'D'n is also recommended if the text should be always visible on two
colour screens or screens with strange pens (e.g. non-newlook (no 3D look)).
If you don't want the problems of a format string, then you can use
bguiaddmap() to put the number in an indicator next to the progress bar.
type 'H' horizontal
     'V' vertical
The amount done is set to zero or the minimum.

obj=bguiindicator(name,[label],min,max,[level],[justify],[format])

Textual level indication gadget.
justify 'L' left (default)
        'C' centre
        'R' right
format: the same thing as in bguiprogress() except that setting colours is
not necessary and that it has a default "%ld".

res=bguiget(obj,attr)

Error descriptions here:
"Invalid keyword" if you supplied an attribute that RexxBGUI does not know -
see "tags" further on in this file for which attributes are available.
"Error return from function" if the obj parameter was not OK or if the
object did not understand the attribute, for example an attribute of another
gadget class or one that is not gettable;
"Wrong number of arguments" if rm->rm_Action & 0xF is not 2 or if
rm_Args[1] or rm_Args[2] is equal to zero.

x=bguiset(obj,[refwin],tag,value,[tag],[value],...)

refwin: window object in which the gadget is located; necessary if you want
visual updating. Specifying another window causes strange results...
If you need to set more than 6 tags, split it out over multiple calls and
omit refwin in all possibly except the last. Put at least one attribute
causing visual update in the last call, if you want any update.

gad=bguireq(text,gadgets,[title],[refwin],[scrname])

RequestChoice/rtEZRequest() like requester. Use '|' to separate the gadgets.
An asterisk adds return as a shortcut for the button it stands before and
escape for the last one. Underscores can be used to prefix keyboard shortcuts.
The window specified by refwin will automatically get a busypointer.
Title defaults to refwin's title, or "BGUI Request" or its localized
equivalent if wndobj is not given.
Scrname does not work.
gad: 1 for the first, 2 for the second, etc. and 0 for the last gadget.

success=bguiaddmap(srcobj,dstobj,sattr,dattr)

This function connects two objects so srcobj will update dstobj's dattr
when its sattr changes. This happens even without bguiwinevent().

Example usages:
Listview with connected string gadget:
call bguiaddmap(obj.listv,obj.str,LISTV_Entry,STRINGA_TextVal)
Listview to select a page (#of listview entries must be #of pages!!!):
call bguiaddmap(obj.listv,obj.pages,LISTV_EntryNumber,PAGE_Active)

The number of attributes that can cause notification (sattr) or be updated
(dattr) is more limited than the number that can be used with bguiget() or
bguiset(). If notification does not work, you'll have to fall back to the
latter mechanism.

There is no "initial" notification.

Notification of LGO attributes may cause a crash. Using bguiset() is safer.

success=bguiaddcondit(srcobj,dstobj,iftag,ifval,thtag,thval,eltag,elval)

This function connects two objects so srcobj will update dstobj depending
on its ifattr. This is more or less equivalent to doing this when srcobj's
iftag changes:
IF bguiget(srcobj,iftag)=ifval THEN CALL bguiset(dstobj,thtag,thval),
  ELSE CALL bguiset(dstobj,eltag,elval)
This happens even without bguiwinevent(). See also bguiaddmap().

Integer tags only.

Always test boolean tags for 0 and never for 1.

Example usage:
Yes/No setting that makes a choice impossible:
call bguiaddcondit(obj.check,obj.mx,GA_Selected,0,MX_EnableButton,0,
,MX_DisableButton,0)

MX_DisableButton,n will never change MX_Active. You have to check separately
if the selection is still possible.

If you init the checkbox to on, the first MX button will not be enabled
initially. If you init the checkbox to off and set it to on after this call,
it will be OK.

count=bguilistvgetentries(listvobj,stemname,[type])

type 'A' all
     'S' selected only

success=bguilistvaddentry(listvobj,[refwin],entry,[where],[flags])

where 'H' head
      'T' tail
      'S' sorted
      number add before entry n
flags 'S' select
      'M' multiselect
      '+' make visible by scrolling list if necessary
      '-' do not make visible
'S' or 'M' makes visible automatically unless disabled with '-'

rc=bguilistvcommand(listvobj,[refwin],command)

command 'clear' delete all entries
        'refresh' refresh listview and scroller
        'sort'
        'redraw' redraw all entries only
        'remselected' single-select only; also selects new entry

success=bguilistvreplacesel(listvobj,[refwin],new)

Use this function to replace the first selected entry of a listview by another.
If no entry is selected, a new one is added and selected.

success=bguiwintabcycleorder(winobj,objects)

RexxBGUI can only check the validity of the objects array to a limited
extent: if a multiple of four spaces is intermixed wrong object pointers
are used and a crash can be expected if tab is pressed in the first gadget.

nm=bguimenu(type,[label],[commkey],[flags],[mutualexclude],[id])

Creates a NewMenu structure. Concatenate some of these and pass the result
to bguiwindow(). If IDs (bguiwinevent()) are to be shared between gadgets
and menuitems, create the gadgets first. Do not give a checkbox and a
CHECKIT|TOGGLE item the same ID as it will be impossible to distinguish

type '1' menu title
     '2' item
     '3' subitem
Omitting label gives a separator bar (automatically disabled).
commkey: RAmiga-... shortcut
flags 'DISABLED'
      'CHECKIT' can be checked (not unchecked)
      'CHECKED' has checkmark
      'TOGGLE' specify CHECKIT too
mutualexclude: selecting this CHECKIT item deselects these items
               (bit #x means item #x)
id: may be either a number or a name of a variable
    number: selecting the item generates this ID
    variable: generate a new ID and store it in the variable
    Therefore you can write bguimenu(...,id.quit) and it will
    automatically share its ID with a gadget's, if it is present.

Example:
menu=bguimenu(1,'Project')||,
      bguimenu(2,'About...','?',,,id.about)||,
      bguimenu(2)||,
      bguimenu(2,'Quit','Q',,,id.quit)||,
     bguimenu(1,'Testing')||,
      bguimenu(2,'Have your cake',,'CHECKIT CHECKED','10'b,id.hyc)||,
      bguimenu(2,'Eat it too',,'CHECKIT','01'b,id.eit)||,
      bguimenu(2,'On or off???',,'CHECKIT TOGGLE',,id.ooo)||,
      bguimenu(2)||,
      bguimenu(2,'Subitems')||,
       bguimenu(3,'Subitem #1','1',,,id.sub1)||,
       bguimenu(3,'Subitem #2','2',,,id.sub2)||,
       bguimenu(3,'Subitem #3','3','DISABLED',,id.sub3)

success=bguiwindisablemenu(winobj,id,state)


success=bguiwincheckitem(winobj,id,state)


rc=bguiwinmenudisabled(winobj,id)

rc 1 disabled
   0 enabled
   -1 unknown menu/no menus at all attached to window

rc=bguiwinitemchecked(winobj,id)

rc 1 checked
   0 not checked
   -1 unknown menu/no menus at all attached to window

success=bguiactivategadget(gadget,refwin)

This call may fail, although that's usually not a severe problem...
RexxBGUI can only check the validity of the objects to a limited extent.

x=bguiclose()

This MUST be called before exiting the script.

success=bguireadentries(filename,stemname)

When using READLN(), EOF cannot be distinguished from an empty line.
Therefore this function is present. It reads lines from a file to a stem
in a format suitable for the listview gadget.

stemname=bguilist(stemname,entry0,[entry1],...)

This function allows you to place small lists (<=14 entries) for listviews
directly in the gadget creation function, a bit like in E [e0,e1,...].
It sets stemname.COUNT and stemname.x (0<=x<stemname.COUNT)

Example:
...
bguilistview('switcher',,bguilist('pnames','Single-Select','Multi-Select'))||,
...
drop pnames. /* not really necessary */

x=bguierror(code)

This function causes an ARexx error, e.g. bguierror(12) causes "Error return
from function".

TAGS: General information

Types:
INT=integer, may be boolean (0 means false, anything else means true)
STRING=string
OBJECT=4-byte pointer

Applicability: ISGNU
I=Init (not applicable for RexxBGUI)
S=Set (bguiset())
G=Get (bguiget())
N=Notify (bguiaddmap() sattr/bguiaddcondit() ifattr)
U=Update (bguiaddmap() dattr/bguiaddcondit() thattr/elattr)
-=not possible
?=not known to me, try it

WINDOW_#? TAGS

WINDOW_Window                 OBJECT --G--

INFO_#? TAGS

INFO_TextFormat               STRING IS--U
INFO_MinLines                 INT
INFO_FixTextWidth             INT

STRINGA_#? TAGS

STRINGA_TextVal               STRING ISGNU makes string gadget
STRINGA_LongVal               INT    ISGNU makes integer gadget
STRINGA_MaxChars              INT    I-?--
STRINGA_BufferPos             INT    IS??? cursor position
STRINGA_DispPos               INT    IS??? first char visible

LGO_#? TAGS

LGO_FixWidth                  INT
LGO_FixHeight                 INT
LGO_Weight                    INT
LGO_FixMinWidth               INT
LGO_FixMinHeight              INT
LGO_Align                     INT
LGO_NoAlign                   INT
LGO_FixAspect                 INT    65536*x+y 41.8 only
LGO_Visible                   INT

LISTV_#? TAGS

LISTV_Top                     INT    ISG-U
LISTV_ReadOnly                INT    ISG?? S/U will not change frame
LISTV_MultiSelect             INT    IS?-U
LISTV_Select                  INT    -S--U
LISTV_MakeVisible             INT    -S--U
LISTV_Entry                   STRING ---N-
LISTV_EntryNumber             INT    ---N-
LISTV_LastClicked             STRING --G--
LISTV_LastClickedNum          INT    --G--
LISTV_NewPosition             INT    ---N-
LISTV_NumEntries              INT    --G--
LISTV_MinEntriesShown         INT    ISG??
LISTV_SelectMulti             INT    -S--U
LISTV_SelectNotVisible        INT    -S--U
LISTV_SelectMultiNotVisible   INT    -S--U
LISTV_MultiSelectNoShift      INT    IS--U
LISTV_Deselect                INT    -S--U
LISTV_DropSpot                INT    --G--
LISTV_ShowDropSpot            INT    IS---
LISTV_Columns                 INT    I-G--
LISTV_DragColumns             INT    ISG-U
LISTV_Titles                  STRING I-G-U 41.8 Enforcer hits
LISTV_Titles!                 OBJECT ISG-U static string problem
LISTV_PreClear                INT    ISG--
LISTV_LastColumn              INT    --G--

GA_#? TAGS

GA_Disabled                   INT    IS?-U
GA_Selected                   INT    ISGNU toggles/checkboxes only

BT_#? TAGS

BT_LabelClick                 INT    IS---
BT_DragObject                 INT    ISG--
BT_DropObject                 INT    ISG--
BT_Key                        STRING ISG-- set after creating window object only
BT_RawKey                     INT    ISG-- set after creating window object only
BT_Qualifier                  INT    ISG-- set after creating window object only

PAGE_#? TAGS

PAGE_Active                   INT    ISG?U

MX_#? TAGS

MX_Active                     INT    ISGNU
MX_DisableButton              INT    IS--U
MX_EnableButton               INT    IS--U

PROGRESS_#? TAGS

PROGRESS_Min                  INT    IS---
PROGRESS_Max                  INT    IS---
PROGRESS_Done                 INT    ISGNU

INDIC_#? TAGS

INDIC_Level                   INT    IS--U

TAG_#? TAGS

TAG_IGNORE                    INT    IS--U does nothing!